Skip to content

docs: add host to new Request()#21709

Open
cyco130 wants to merge 2 commits intovitejs:mainfrom
cyco130:patch-1
Open

docs: add host to new Request()#21709
cyco130 wants to merge 2 commits intovitejs:mainfrom
cyco130:patch-1

Conversation

@cyco130
Copy link
Contributor

@cyco130 cyco130 commented Feb 25, 2026

The FetchableDevEnvironment examples in the docs use bare URLs with the Request constructor like new Request('/request-to-handle') but in Node, this constructor requires a full URL with a host, otherwise a TypeError: Failed to parse URL from /request-to-handle will be thrown.

But this is not a complete fix, we need to explain where the HOST_NAME constant will come from and what it should contain. If we don't care about the actual host, a simple http://example.com will work but it would be confusing and require some explanation at least. UPDATE: Changed host name to http://example.com.

Opening this PR to start the discussion.

The examples in the docs use bare URLs with the `Request` constructor like `new Request('/request-to-handle')` but in Node, this constructor requires a full URL with a host, otherwise a `TypeError: Failed to parse URL from /request-to-handle` will be thrown.

But this is not a complete fix, we need to explain where the `HOST_NAME` constant will come from and what it should contain.

Opening this PR to start the discussion.
@bluwy
Copy link
Member

bluwy commented Feb 26, 2026

I think I would prefer using http://example.com instead, because HOST_NAME also isn't clear what its value should be or if it matters. I think in a lot of cases the host name doesn't really matter.

@bluwy bluwy changed the title fix(docs): new Request() will not work without a host docs(api-environment-frameworks): add host to new Request() Feb 26, 2026
@bluwy bluwy changed the title docs(api-environment-frameworks): add host to new Request() docs: add host to new Request() Feb 26, 2026
@sapphi-red sapphi-red added the documentation Improvements or additions to documentation label Feb 26, 2026
@sapphi-red
Copy link
Member

I guess we should also clarify that the host part will be overwritten by the environment (so that it can send that request to the runtime where the module runner lives).

@sapphi-red sapphi-red requested a review from hi-ogawa February 26, 2026 07:18
@hi-ogawa
Copy link
Contributor

I feel the issue is that just the doc here is the vague since new Request shouldn't need to appear out of nowhere. For actual use case, there should be configureServer and Node request to Web request conversion etc. I'd imagine that can clarify it better. But I think just fixing host here is also fine to start with, so for that, I'd vote for writing out host name like example.com or localhost.

@cyco130
Copy link
Contributor Author

cyco130 commented Feb 26, 2026

It's not uncommon to change routing rules for different origins (free.example.com might lack some of the routes on paid.example.com) but I suppose it can be considered not critical for dev.

I left a comment on the FetchableDevEnvironment proposal some months ago suggesting something like "proxyable" instead of (or in addition to) "fetchable" could be more useful, because I'd expect most of the time the transport to be HTTP and proxying can do things that fetch can't (like keeping the original host header). I'll leave another comment in that discussion.

For now, I changed HOST_NAME to example.com.

Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

documentation Improvements or additions to documentation

Projects

None yet

Development

Successfully merging this pull request may close these issues.

4 participants